<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Additional Control and Support
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot032.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot034.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc60">6.7</A>&nbsp;&nbsp;Additional Control and Support</H2><UL>
<LI><A HREF="embroot033.html#toc29">Initialisation During Attachment</A>
<LI><A HREF="embroot033.html#toc30">Disconnection and Control Transfer Support</A>
</UL>

<A NAME="remote-control"></A>
The remote interface provides additional support for controlling the
interaction of the Tcl and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> sides, such as explicit transfer of
control between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Tcl, and the disconnection of the Tcl
and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> sides. The interface also provides support for special
user-defined commands to be executed during these events.<BR>
<BR>
<A NAME="toc29"></A>
<H3 CLASS="subsection"><A NAME="htoc61">6.7.1</A>&nbsp;&nbsp;Initialisation During Attachment</H3>
In an application, after the Tcl side has been attached, typically some
application specific initialisation needs to be performed, such as setting
up various data queues between the two sides, and defining the actions to
take when the two sides are disconnected. On both sides, these
initialisations can be performed immediately after attachment. On the Tcl
side, such
actions can be specified in the optional <I>init_command</I> argument of
<I>ec_remote_init</I>. On the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, such actions can be specified
in the `InitGoal' (last) argument of <I>remote_connect/3</I>. InitGoal can
be a built-in, or a user-defined goal.<BR>
<BR>
<A NAME="toc30"></A>
<H3 CLASS="subsection"><A NAME="htoc62">6.7.2</A>&nbsp;&nbsp;Disconnection and Control Transfer Support</H3>
Disconnection should normally be performed when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> application
has finished using the GUI provided by the particular attached remote process.
The disconnection
may be initiated from either side. In addition to cleaning up and closing
all the remote queues connecting the two sides, the disconnection would
trigger the execution of user definable procedures on both sides (through an
event on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, and a call-back on the Tcl side), which can
be used to perform extra application specific cleanup and shutdown
routines. <BR>
<BR>
For the transfer of control from Tcl to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and vice versa, 
user-definable call-backs are made. This is to enable to define application
specific restrictions on what the GUI is allowed to do when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side has the control (for example, the GUI may have a button that sends an
rpc goal to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> when pressed. Such a button could be disabled by the
call-back when control is transferred to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and reenabled when
control is transferred back to Tcl).<BR>
<BR>
Note that there are two types of transfer of control from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to
Tcl: 1) when the control is implicitly yielded (e.g. initiating I/O
from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> with Tcl, or returning after an rpc call); 2) when the
control is handed over by yielding explicitly (e.g. by calling
<A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default145"></A> in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>). With implicit yield, the Tcl side is
expected to eventually handed back control implicitly to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, and
not to explicitly hand control over to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> before this. Thus two
call-backs are provided when control is yield to Tcl: one is executed
whenever the control is yielded, and the other is only executed when the
control is explicitly yielded. Thus when control is explicitly yielded,
both call-backs are executed. This can be useful for example by defining
the explicit yield call-back to enable a button on the Tcl side that will
explicitly transfer control back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> when pressed, which should
only be enabled when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> explicitly yielded to Tcl.<BR>
<BR>
On the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, an event is raised when the two sides
disconnect. The event's name is the control stream's name. The user can
define a handler for this event to allow user-defined action to take place
on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side on disconnection. The simplest way to define this
handler is to do it during the connection, via the last argument of <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default146"></A>.<BR>
<BR>

<H4 CLASS="subsubsection">Tcl side</H4>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default147"></A><B>ec_running</B><DD CLASS="dd-description"><BR>
	checks if the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side has control. Returns 1 if ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
	side has control, 0 otherwise. If that is the case,
	then the Tcl side cannot issue an ec_rpc goal. Note that ec_running
	will return 1 before connection and after disconnection.
<DT CLASS="dt-description"><A NAME="@default148"></A><B>ec_connected</B><DD CLASS="dd-description"><BR>
checks if the Tcl side is currently attached to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Returns
 1 if there is a connection to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (i.e. it is attached), 0
 otherwise. 
<DT CLASS="dt-description"><A NAME="@default149"></A><B>ec_resume</B><DD CLASS="dd-description"><BR>
	explicitly hand-over control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Tcl side must have
	control when this command is called (i.e. <I>ec_running</I> must
	be false). This command returns when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side yields the
	control back to the Tcl side. Meanwhile, the Tcl process is not
 suspended as the Tcl event loop is entered while waiting for the
	yield. 
<DT CLASS="dt-description"><A NAME="@default150"></A><B>ec_running_set_commands <I>?start? ?end? ?yield? ?disconnect?</I></B><DD CLASS="dd-description"><BR>
	set up commands that will be called just before control is handed
	over to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (<I>start</I>), when control is handed back from
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (<I>end</I>), when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> explicitly yields control
	(<I>yield</I>), and when the Tcl side is
	disconnected by the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side (<I>	disconnect</I>). The <I>start</I> and <I>end</I> commands are called
	both when control change hands explicitly (e.g. via <I>	ec_resume</I>), or implicitly (e.g. by making an rpc call or
	performing I/O on a synchronous remote queue). An explicit yield
	from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will in addition call the <I>yield</I> command, <I>	after</I> the <I>start</I> command is executed.<BR>
<BR>
	The default for each command is that no command will be called.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default151"></A><B>ec_disconnect <I>?side?</I></B><DD CLASS="dd-description"><BR>
	disconnect the Tcl process from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process. This closes
	all the connections between the two sides. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will
	abort from what it was doing. After disconnection, the
	two sides can no longer communicate, and <I>ec_running</I> will be
	set. The optional argument <I>side</I> specifies which side, tcl
	or eclipse,
	initiated the disconnection. For user's Tcl program, this will
	normally be the default tcl. If the disconnect is initiated from
	the Tcl side, this command will cause the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side to also
	close its connections to this remote connection, as well as
	raising the disconnect event in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> associated with this
	remote connection. If the disconnect was initiated from
	the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, then <I>ec_disconnect</I> will be called
	automatically with <I>side</I> set to eclipse, and the disconnect
	command set up by <I>ec_running_set_commands</I> will be executed.
</DL>

<H4 CLASS="subsubsection">ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side</H4>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default152"></A><B>remote_yield(+Control)</B><DD CLASS="dd-description"><BR>
	Explicitly yields control from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to the remote side with
	the control stream <I>	Control</I>. ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution will suspend
	until control is transferred back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. This predicate
	returns when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side resumes control.
	
<DT CLASS="dt-description"><A NAME="@default153"></A><B>remote_disconnect(+Control)</B><DD CLASS="dd-description"><BR>
	Initiates disconnection from the remote side specified by <I>	Control</I>. This will close all connections between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and
	the remote side, on both sides. It will also cause an event <I>	Control</I> to be raised. 
</DL>
Note that if the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process is halted normally, then ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
will try to disconnect from every remote side it may be connected to.<BR>
<BR>
<HR>
<A HREF="embroot032.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot034.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
